Developer CD Series 1998 August: Tool Chest/Dev.CD Aug 98 TC.toast/Tool Chest/Testing & Debugging/Mac OS Development Toolkit/Automation Essentials 2.3.0/Host Automation Folder/SPEC Libs/TimingBasics.Lib

Text File | 1998-03-19 | 24.5 KB | 655 lines | [TEXT/MPS ]

#
# ****************************************************************************
#
#    File Name:    TimingBasics.lib
#
#    Contains:    Lower level timing routines
#
#    Written by:    KTA
#
#    Copyright:    © 1993-1995 by Apple Computer, Inc., all rights reserved.
#
# ****************************************************************************
#            C h a n g e        H i s t o r y (most recent first):
# ****************************************************************************
#
#        Vers      Date        Author        Description
#        ----    --------    ------    ---------------------------------------------
#        <13>     2/28/95    ML        marked
#        <12>     2/14/95    KTA        Polling() -     Added BooleanFlag to FindWindow() call
#        <11>     1/31/95    ML        add IvyOperations.Lib to declaration, change all ivy calls to
#                                    _Ivy calls
#        <10>     1/19/95    KTA        Changed the name of ExceptionHandler() to ExceptionDispatcher().
#         <9>     12/6/94    ML        Added Exception Handling support
#         <8>     7/13/94    ML        Added comments
#         <8>     7/13/94    ML        Added comments
#         <7>     6/28/94    ML        EndTimerIV() - bail out of infinite loop in endTime is
#                                    continously 0
#         <6>     6/23/94    ML        Move hook for MacsTiming in StartTimerIV() to before IV call
#         <5>     6/20/94    ML        LogPerformanceResults() - If defined, use global kTCSetDefault
#                                    instead of gApptitle in TCSStart() call
#         <4>     4/18/94    ML        Added gStopTimerIVHook1, gStopTimerIVHook2 to globals
#                                    declaration in StopTimerVU()
#         <3>     4/15/94    KTA        Moved some tasks to MacsTimeOperations.Lib, Removed some tasks,
#                                    etc.
#         <2>     4/13/94    KTA        Changed gDBLogging to gTCTracking
#         <1>     4/12/94    ML        Moved into Libraries project
#     <1.0.6>     4/12/94    ML        added InitPerformance().  To  InitPerformance(), added
#                                    SuiteStart params, pInitialMethod, pPerformanceLoggingOnly,
#                                    MacsTime CDev launch and hook installation, removed
#                                    gInitPerformanceHook1, remove and reset MacsTime hooks during
#                                    ReplaceExist (modal disables Apple Events).  Added
#                                    EndPerformance().  To EndPerformance(), added pCompletionCode,
#                                    added check for MacsTime (MTControl), removed
#                                    gEndPerformanceHook1, added SuiteEnd(), reset and restore
#                                    gTCTracking.  Added TimedEventDescription().  Added
#                                    LogPerformanceResults().  To  LogPerformanceResults(), renamed
#                                    from LogPerformTCS, add support for pTCSStr, notebook printout
#                                    of results.  Replace stoptimer w/stoptimerVU, replace stoptimer
#                                    w/stoptimerVU, remove global gTiming.      StartTimerVU()-changed
#                                    global StartTime to gStartTime, added generic hook -
#                                    gStartTimerVUHook,renamed from StartTimer, use gTimedEvent
#                                    instead of gTiming, only call if gTimedEvent is defined, removed
#                                    MacsTiming calls (use gStartTimerVUHook instead).
#                                    StartTimerIV() - don't run unless gTimedEvent is true, added
#                                    gStartTimerIVHook. StopTimerIV() - don't run unless gTimedEvent
#                                    true, removed gTiming, add gStopTimerIVHook1, gStopTimerIVHook2,
#                                    added event description, pStopTimerHook, call
#                                    LogPerformanceResults to log TCS's (whew!).
#     <1.0.5>     3/29/94    KTA        FormatMilliSeconds() now handle integer values.
#     <1.0.4>     3/11/94    KTA        Fixed bug in FormatMilliSeconds() and added parameter to
#                                    StopTimerIV().
#     <1.0.3>    11/18/93    KTA        Added ¶ character to output lines for performance for timings in
#                                    VU also.
#     <1.0.2>    11/18/93    KTA        Added ¶ character to output lines for performance.
#        <1>         11/16/93    KTA        Created
#
# ****************************************************************************
#


########################################################################
#                            External libraries
#=======================================================================
Libraries "Utility.Lib", 'UserInterface.Lib', 'IvyOperations.Lib', 'TCS.Lib',
"ExceptionHandling.Lib", 'Ivy.vulib';



#########################################################################
#                         InstallVUTimingMethod()
#=======================================================================
# Author:              KTA
# Description:        Initializes the task references required to complete
#                    performance testing utilizing VU.
# Parameters:        none
# Returns:            Nothing
# Example:            InstallVUTimingMethod();
# Assumptions        This task must be called prior to doing any performance
#                    testing with SPEC S&L
#=======================================================================
# History:
# ML    3/30/94    Changed StartTimer to StartTimerVU
#########################################################################
TASK InstallVUTimingMethod()
begin
    global gPreSelectMenuItemHook     :=     task StartTimerVU;
    global gPostSelectMenuItemHook     :=     task StartTimerVU;
    global gPreKeyEqHook            :=     task StartTimerVU;
    global gPreSelectButtonHook     :=     task StartTimerVU;
    global gPreMoveMouseHook         :=     task StartTimerVU;
    global gPreSpecialKeyHook         :=     task StartTimerVU;
end;


#########################################################################
#                         RemoveVUTimingMethod()
#=======================================================================
# Author:              KTA
# Description:        Removes the the task references required to complete
#                    performance testing utilizing VU.
# Parameters:        none
# Returns:            Nothing
# Example:            RemoveVUTimingMethod();
# Assumptions        This task can be called after to doing any performance
#                    testing with SPEC S&L you want to remove any effects of
#                    the performance testing.
#=======================================================================
# History:
#########################################################################
TASK RemoveVUTimingMethod()
begin
    global gPreSelectMenuItemHook     :=     0;
    global gPostSelectMenuItemHook     :=     0;
    global gPreKeyEqHook            :=     0;
    global gPreSelectButtonHook     :=     0;
    global gPreMoveMouseHook         :=     0;
    global gPreSpecialKeyHook         :=     0;
end;

#########################################################################
#                         InstallIVTimingMethod()
#=======================================================================
# Author:              KTA
# Description:        Initializes the task references required to complete
#                    performance testing utilizing IVY.
# Parameters:        none
# Returns:            Nothing
# Example:            InstallIVTimingMethod();
# Assumptions        This task must be called prior to doing any performance
#                    testing with IVY
#=======================================================================
# History:
# KTA     4/13/94    Changed gDBLogging to gTCTracking
# KTA     4/14/94    Moved Standard file hooks to the StandardFile tasks
#########################################################################
TASK InstallIVTimingMethod()
begin
    global gPreSpecialKeyHook := task StartTimerIV;
    global gPreSelectButtonHook := task StartTimerIV;
    global gPreKeyEqHook := task StartTimerIV;
end;


#########################################################################
#                         RemoveIVTimingMethod()
#=======================================================================
# Author:              KTA
# Description:        Removes the the task references required to complete
#                    performance testing utilizing IVY.
# Parameters:        none
# Returns:            Nothing
# Example:            RemoveIVTimingMethod();
# Assumptions        This task can be called after to doing any performance
#                    testing with IVY and you want to remove any effects of
#                    the performance testing.
#=======================================================================
# History:
# KTA     4/13/94    Changed gDBLogging to gTCTracking
# KTA     4/14/94    Moved Standard file hooks to the StandardFile tasks
# ML    1/31/95    Use _Ivy calls
#########################################################################
TASK RemoveIVTimingMethod()
begin
    global gPreSpecialKeyHook := 0;
    global gPreSelectButtonHook := 0;
    global gPreKeyEqHook := 0;
    _Ivy(task IVStopWaitForImage);

    #IVQuit();
end;




#########################################################################
#                             StartTimerVU
#=======================================================================
# Author:              KTA/DM
# Description:        Begin the Timer with VU
# Parameters:        none
# Returns:            none
# Example:            StartTimerVU();
#
#    StartTimer will get called many more times than are actually timed.
#    Timing will occur only if StopTimer is called and global gTimedEvent is TRUE
#    gTimedEvent should also be set to the title of the timed test.
#=======================================================================
# History:
# ML    3/30/94    changed  global StartTime to gStartTime
# ML    3/30/94    Added generic hook - gStartTimerVUHook
# ML    3/30/94    Renamed from StartTimer
# ML    3/30/94    use gTimedEvent instead of gTiming
# ML    3/30/94    only call if gTimedEvent is defined
# ML    3/30/94    removed MacsTiming calls (use gStartTimerVUHook instead)
#########################################################################
task StartTimerVU()
begin
    global gStartTime, gTimedEvent, gStartTimerVUHook;
    if gTimedEvent
    begin
        gStartTime := Timer();            # Start that Timer
        if (gStartTimerVUHook)
            call (gStartTimerVUHook);    # hook for MacsTime, etc.
    end;
end;

#########################################################################
#                     StopTimerVU(polling := 1, specifier := '', pStopTimerHook := 0)
#=======================================================================
# Author:              DM/KTA/JH
# Description:        subtracts the last time saved by StartTimerVU from the current time
#                    and outputs the event name and the elapsed seconds
# Parameters:        polling, specifier see Polling()
#                    pStopTimerHook - name of custom task defined in calling script
# Returns:            Elapsed time in secs if success, 0 if failure
# Example:            ETime(time1, time2);
#=======================================================================
# History:
# ML    3/30/94    changed  global StartTime to gStartTime
# ML    3/31/94    Renamed to StopTimerVU, removed gTiming, add gStopTimerVUHook1,
#                gStopTimerVUHook2,
#                remove calls to MacsTime (use gStopTimerVUHook1, gStopTimerVUHook2
#                instead), added return value, assigned event description, change
#                StopTimerHook to pStopTimerHook, define ResultCode and ErrorString,
#                call LogPerformanceResults to log TCS's (whew!)
# KTA     4/13/94    Changed gDBLogging to gTCTracking
#########################################################################
task StopTimerVU(polling := 1, specifier := '', pStopTimerHook := 0)
begin
    global gStartTime, gTimedEvent, gMacstimeApp, gMacsTiming,
    gStopTimerVUHook1, gStopTimerVUHook2, gAppTitle;
    returnval := 0;
    if (gTimedEvent)
    begin

        if(polling)
            Polling(polling, specifier);

        endTime := Timer();                # Save Off the current time

        myEvent := TimedEventDescription();

        if (pStopTimerHook)
            Call(pStopTimerHook);

        if (gStopTimerVUHook1)    #    hook for MacsTime, etc.
            Call (gStopTimerVUHook1, myEvent);

        ##### Calculate the Elapsed Time, log Test Case

        if ((isUndefined(gStartTime)) or (gStartTime = 0))
        begin
            ResultCode := 0;
            ErrorString := "the elapsed time routine didn't work - gStartTime is {gStartTime}!!!)";
            ElapsedTime := 0;
        end;
        else
        begin
            ResultCode := 1;
            ErrorString := '';
            ElapsedTime := ETime(gStartTime,endTime,0);
            returnval := ElapsedTime;
        end;

        LogPerformanceResults (ResultCode,ErrorString,ElapsedTime);

        gTimedEvent := '';    # reset

        if gStopTimerVUHook2    #    hook for MacsTime, etc.
            call (gStopTimerVUHook2, myEvent);

        gStartTime := 0;

    end; # if (gTimedEvent)
    return (returnval);
end;

#########################################################################
#                             Polling(PollMethod, Specifier)
#=======================================================================
# Author:              KTA
# Description:        Polls until target machine is available or until specifier
#                    is located/gone.
# Parameters:        polling <> 0    poll before completing
#                     specifier = ''    match the target when polling
#                     specifier <> ''    & polling > 0
#                            poll until the specifier is matched
#                     specifier <> ''    & polling < 0
#                            poll until the specifier is not matched
# Returns:
# Example:            Polling(1, {[window t:'Untitled' o:2]});
#=======================================================================
# History:
#    ML    8/12/93        Added support for any descriptor
# KTA    2/14/95    Added BooleanFlag to FindWindow() call
#########################################################################
TASK Polling(PollMethod := 0, specifier := '')
begin
    if not (specifier) # just match the target
    begin
        try thisCheck := match [target t:?Mytarget]!;
        catch theError
            ExceptionDispatcher(theError);
        while not (thisCheck)            #### Polling Generic ####
        begin
            try thisCheck := match [target t:?Mytarget]!;
            catch theError
                ExceptionDispatcher(theError);
        end;

        if (PollMethod = 2)         # This was put in for a VU bug will be removed
            while not (_matchBoolean ([application]!));
    end;
    else     # match for the specifier
    begin
        if TypeOf(specifier) = 'descriptor'
        begin
            if descType(specifier) <> 'window'
            begin                            # generalized polling method
                if(PollMethod > 0)             #### Polling - wait for descriptor ####
                    while not (_matchBoolean (specifier!));
                else                          #### Polling - wait for descriptor to go away ####
                begin    #do this if PollMethod is negative
                    while (_matchBoolean (specifier!));
                end;
            end;
        end;
        if (TypeOf(specifier) <> descriptor) or (descType (specifier) = 'window')
        begin
        if(PollMethod > 0)             #### Polling - wait for window ####
            while not (FindWindow(specifier, true)) ;
        else                          #### Polling - wait for window to go away ####
        begin    #do this if PollMethod is negative
            while (FindWindow(specifier, true));
        end;
    end;
    end;
end;


#########################################################################
#                         StartTimerIV()
#=======================================================================
# Author:              KTA
# Description:        Calls IVStartWaitForImage() and sets a variable <gStartTimerIV)
#                     to the current the current time in milliseconds. Note: IVStopWaitForImage()
#                    is called first in case IVStartWaitForImage() has already been called.
# Parameters:        None
# Returns:            Nothing - but sets gStartTimerIV to the currenttime in Milliseconds
# Example:            StartTimerIV();
# Assumptions        Ivy exists on the target machine and has been initialized.
#=======================================================================
# History:
#    ML    3/31/94    Don't run unless gTimedEvent is true, added gStartTimerIVHook
#    ML    6/23/94    Move hook for MacsTiming in StartTimerIV() to before IV call
#    ML    1/31/95    Use _Ivy calls
#########################################################################
task StartTimerIV()
begin
    global gImageFile, gRect, gStartTimerIVHook, gTimedEvent, gStartTimerIV;
    if gTimedEvent
    begin
        _Ivy(task IVStopWaitForImage);
        if (gStartTimerIVHook)
            call (gStartTimerIVHook);                # hook for MacsTime, etc.
        gStartTimerIV := _Ivy(task IVStartWaitForImage,{gImageFile, gRect,5});
    end;
end;

#########################################################################
#                         StopTimerIV()
#=======================================================================
# Author:              KTA
# Description:        Calls IVGetTimeFound() and sets a variable <endTime>
#                     to the current the current time in milliseconds. It then
#                    calls IVSubtractTimes() to get the difference between global
#                    <gStartTimerIV> and <endTime>.  Then the IV and appleEvent overhead
#                    is subtracted.
# Parameters:        pWaitTime - Time to wait this can be longer than it takes the image to
#                                appear, but must not be shorter.
#                    pStopTimerHook - name of custom task defined in calling script
#
# Returns:            NetTime2 - success, difference between gStartTimerIV and Endtime with overhead
#                                subtracted.
#                    0 - failure
# Example:            StopTimerIV();
# Assumptions        Ivy exists on the target machine and has been initailized.
#                    Also requires that a call to StartTimerIV() was made prior to
#                    calling this routine.
#=======================================================================
# History:
# KTA    3/10/94    Added pWaitTime
# ML    3/31/94    Don't run unless gTimedEvent true, removed gTiming, add gStopTimerIVHook1,
#                gStopTimerIVHook2, added event description, pStopTimerHook,
#                call LogPerformanceResults to log TCS's (whew!)
# ML    4/18/94    Added gStopTimerIVHook1, gStopTimerIVHook2 to globals declaration
# ML    6/27/94    bail out of infinite loop if endTime is continously 0
# ML    1/31/95    Use _Ivy calls
#########################################################################
task StopTimerIV(pWaitTime := 10, pStopTimerHook := 0)
begin
    global gTimedEvent, gStopTimerIVHook1, gStopTimerIVHook2;
    returnval := 0;
    if (gTimedEvent)
    begin
        wait(pWaitTime);
        endTime := IVGetTimeFound();
        myEndCounter := 1;        # Initialize your counter
        while (endTime = '0') # IVGetTimeFound returns a string
        begin
            if myEndCounter < 13    # only loop through 12 times (1 minute)
            begin
                wait(5);
                endTime := _Ivy(task IVGetTimeFound);
                myEndCounter := myEndCounter + 1;
            end;
            else
                endTime := 0;
        end;

        myEvent := TimedEventDescription();

        if (pStopTimerHook)
            Call(pStopTimerHook);

        if (gStopTimerIVHook1)    #    hook for MacsTime, etc.
            Call (gStopTimerIVHook1, myEvent);

        if (endTime) # if valid endTime
        begin # if valid endTime

            ### Calculate the elapsed time

                #println "This is global gStartTimerIV - ", global gStartTimerIV;
                #println "This is endTime - ", endTime;
            TotalTime := _Ivy(task IVSubtractTimes, {endTime, global gStartTimerIV[1]});
                #println "This is TotalTime - ", TotalTime;
            global gStartTimerIV := 0;    # Reset it
            theRoundTrip := _Ivy(task IVCallOverhead);
                #println "    This is theRoundTrip - ", theRoundTrip;

            NetTime1 := _Ivy(task IVSubtractTimes, {TotalTime, theRoundTrip});
                #println "This is NetTime1 - ", NetTime1;

            TimeUsed := _Ivy(task IVStopWaitForImage);
                #println "    This is TimeUsed - ", TimeUsed;

            NetTime2 := _Ivy(task IVSubtractTimes, {NetTime1, TimeUsed});
            ElapsedTime := FormatMilliSeconds(NetTime2);
            returnval := ElapsedTime;

            LogPerformanceResults(1,,ElapsedTime);

        end; # if valid endTime
        else # else endTime is invalid
        begin
            LogPerformanceResults(0,"Endpoint image not found");
            println "WARNING - Endpoint image was not found -
            check your IVY wait times";
        end; # if invalid endTime

        gTimedEvent := '';    # reset

        if (gStopTimerIVHook2)    #    hook for MacsTime, etc.
            Call (gStopTimerIVHook2, myEvent);

    end; # if (gTimedEvent)
    return(returnval);
end;


#########################################################################
#     LocateTheString( pTheRect, theString, theFont, theSize, theStyle  )
#=======================================================================
# Author:              KTA
# Description:        Makes a call to IVLocateString() to locate a string with the attributes
#                    of the parameters and returns the rect of the found string.
# Parameters:        pTheRect - the rect to begin looking for the string in.
#                    theString - the actual text of the string to look for.
#                    theFont - the font title of theString.
#                    theSize - the size of theString.
#                    theStyle - the style of theSting.
# Returns:            the rect of theString that was found on target machine.
# Example:            LocateTheString({0,0,480, 640}, 'Hello World', 'Times', 10, 0);
# Assumptions        Ivy exists on the target machine and has been initialized.
#=======================================================================
# History:
# ML    1/31/95    Use _Ivy calls
#########################################################################
task LocateTheString( pTheRect, theString := "Stop", theFont := "Geneva", theSize := 12, theStyle := 0  )
begin
    resultList := _Ivy(task IVLocateString, {theString, pTheRect, theFont, theSize, theStyle});
    if ( resultList = { 0, 0, 0, 0 } )
    begin
        println "Error - Ivy could not find, and therefore could not create the end point image.";
        Exit;
    end;
    waitingRectangle := resultList;
    return (waitingRectangle);    # return the end point rectangle.
end; # LocateTheString()

#########################################################################
#                 FormatMilliSeconds( pTimeInMilliseconds )
#=======================================================================
# Author:              KTA
# Description:        Formats a time value in milliseconds by adding a decimal
#                    point to seperate the integer portion from the fractional
#                    portion.
# Parameters:        pTimeInMilliseconds - a string or integer which is a time
#                            value in milliseconds.
# Returns:            String - Formated value.
# Example:            x := FormatMilliSeconds('76543');
#=======================================================================
# History:
# KTA    3/10/94    Fixed problem when pTimeInMilliseconds was < 3 digits
# KTA    3/15/94    Added support for pTimeInMilliseconds to be an integer.
#########################################################################
TASK FormatMilliSeconds(pTimeInMilliseconds := '')
begin
    if (TypeOf(pTimeInMilliseconds) = 'integer')
        pTimeInMilliseconds := NumToStr(pTimeInMilliseconds);

    IntegerPortion := 0;
    LenghtOfTimeValue := card(pTimeInMilliseconds);
    FormatedValue := '';

    if(LenghtOfTimeValue >= 3)
    begin
        IntegerPortion := LenghtOfTimeValue-3;
        for i := 1 to IntegerPortion
            FormatedValue := FormatedValue + pTimeInMilliseconds[i];
    end;
    else
    begin
        if(LenghtOfTimeValue = 2)
            pTimeInMilliseconds := '0' + pTimeInMilliseconds;
        else if (LenghtOfTimeValue = 1)
            pTimeInMilliseconds := '00' + pTimeInMilliseconds;

        LenghtOfTimeValue := card(pTimeInMilliseconds);
    end;

    FormatedValue := FormatedValue + '.';

    for n := (IntegerPortion +1) to LenghtOfTimeValue
        FormatedValue := FormatedValue + pTimeInMilliseconds[n];

    #println "This is the FormatedValue - ", FormatedValue;

    return(FormatedValue);
end;

#########################################################################
#             LogPerformanceResults()
#========================================================================
#
# Author:        ML
# Description:    Wrapper task for logging a performance result
# Parameters:    pResultCode, pErrStr, pTCSVal, pTCSStr, pCommentStr, pExceptionFlag
#                - see TCSEnd()
# Returns:        none
# Examples:        LogPerformanceResults()
#========================================================================
# History:
# ML    3/31/94    renamed from LogPerformTCS, add support for pTCSStr,
#                notebook printout of results
# KTA     4/13/94    Changed gDBLogging to gTCTracking
# ML    6/8/94    If defined, use global kTCSetDefault instead of gApptitle
#                in TCSStart() call
#########################################################################
TASK LogPerformanceResults(pResultCode := '', pErrStr := '', pTCSVal := 0,
pTCSStr := '', pCommentStr := '', pExceptionFlag := '')
begin
    global gTimedEvent, gAppTitle, kTCSetDefault;

    # parse out gTimedEvent

    if typeof(gTimedEvent) = 'list'
    # if list, first item is the TCS num, second is the event desc, third is TC string
    begin
        myTCNum := gTimedEvent[1];
        myTimedEvent := gTimedEvent[2];
        if gTimedEvent[3]
            pTCSStr := gTimedEvent[3];
    end;
    else
    #if not a list, gTimedEvent is event desc
    begin
        myTCNum := 0;
        myTimedEvent := gTimedEvent;
    end;

    if ((kTCSetDefault = "UnknownSet") or (kTCSetDefault = 0) or (kTCSetDefault = ''))
        myTCid := {myTCNum, gAppTitle, "Performance"};
    else
        myTCid := {myTCNum, kTCSetDefault, "Performance"};

    TCSStart (myTCid, myTimedEvent);
    TCSEnd (myTCid, pResultCode, pErrStr, pTCSVal, pTCSStr, pCommentStr, pExceptionFlag);

    if (pResultCode = 1)
    begin
        if (pTCSStr and  (pTCSStr <> 'undefined'))
            println "{myTimedEvent}    {pTCSStr} {pTCSVal}";            # this is where the printing happens for performance runs
        else
            println "{myTimedEvent} {pTCSVal}";            # this is where the printing happens for performance runs
    end;
    else
    begin
        if (pTCSStr and  (pTCSStr <> 'undefined'))
            println "{myTimedEvent}    {pTCSStr} {pErrStr}";            # this is where the printing happens for performance runs
        else
            println "{myTimedEvent} {pErrStr}";            # this is where the printing happens for performance runs
    end;
end;

#########################################################################
#
#                TimedEventDescription()
#========================================================================
#
# Author:        ML
# Description:    Text description of timed event from gTimedEvent
# Parameters:    none
# Returns:        Text description of timed event
# Examples:        TimedEventDescription()
#========================================================================
# History:
#    ML    3/31/94        Created
#########################################################################
TASK TimedEventDescription()
begin
    global gTimedEvent;
    returnval := 0;
    if (gTimedEvent)
    begin
        if typeof(gTimedEvent) = 'list'
        # if list, first item is the TCS num, second is the event desc
            returnval := gTimedEvent[2];
        else
        #if not a list, gTimedEvent is event desc
            returnval := gTimedEvent;
    end;     # if (gTimedEvent)
    return (returnval);
end;